/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package org.apache.coyote;

import org.apache.tomcat.util.net.SocketEvent;

/**
 * Adapter. This represents the entry point in a coyote-based servlet container.
 *
 * @author Remy Maucherat
 *
 * @see ProtocolHandler
 */
// 适配器。这表示基于 coyote 的 servlet 容器中的入口点
public interface Adapter {

    /**
     * Call the service method, and notify all listeners
     *
     * @param req The request object
     * @param res The response object
     *
     * @exception Exception if an error happens during handling of the request. Common errors are:
     *                          <ul>
     *                          <li>IOException if an input/output error occurs and we are processing an included
     *                          servlet (otherwise it is swallowed and handled by the top level error handler mechanism)
     *                          <li>ServletException if a servlet throws an exception and we are processing an included
     *                          servlet (otherwise it is swallowed and handled by the top level error handler mechanism)
     *                          </ul>
     *                          Tomcat should be able to handle and log any other exception ( including runtime
     *                          exceptions )
     */
    // 调用服务方法，并通知所有侦听器
    // 参数：
    // req – 请求对象 res – 响应对象
    // 抛出：
    // Exception – 如果在处理请求期间发生错误。常见错误包括：
    // IOException，如果发生输入/输出错误并且我们正在处理包含的servlet（否则它将被顶级错误处理程序机制吞噬和处理）
    // ServletException，如果一个servlet抛出一个异常，而我们正在处理一个包含的servlet（否则它会被顶级错误处理程序机制吞噬和处理）
    // Tomcat应该能够处理和记录任何其他异常（包括运行时异常）
    void service(Request req, Response res) throws Exception;

    /**
     * Prepare the given request/response for processing. This method requires that the request object has been
     * populated with the information available from the HTTP headers.
     *
     * @param req The request object
     * @param res The response object
     *
     * @return <code>true</code> if processing can continue, otherwise <code>false</code> in which case an appropriate
     *             error will have been set on the response
     *
     * @throws Exception If the processing fails unexpectedly
     */
    // 准备给定的请求/响应进行处理。此方法要求已使用 HTTP 标头中提供的信息填充请求对象。
    // 参数：
    // req – 请求对象 res – 响应对象
    // 返回：
    // true 如果处理可以继续，否则 false 在这种情况下，将在响应上设置适当的错误
    // 抛出：
    // Exception – 如果处理意外失败
    boolean prepare(Request req, Response res) throws Exception;

    boolean asyncDispatch(Request req, Response res, SocketEvent status) throws Exception;

    void log(Request req, Response res, long time);

    /**
     * Assert that request and response have been recycled. If they have not then log a warning and force a recycle.
     * This method is called as a safety check when a processor is being recycled and may be returned to a pool for
     * reuse.
     *
     * @param req Request
     * @param res Response
     */
    // 断言请求和响应已被回收。如果他们没有，则记录警告并强制回收。当处理器被回收并可能返回到池中以供重用时，此方法称为安全检查。
    void checkRecycled(Request req, Response res);

    /**
     * Provide the name of the domain to use to register MBeans for components associated with the connector.
     *
     * @return The MBean domain name
     */
    //提供用于为与连接器关联的组件注册 MBean 的域的名称。
    // 返回：
    // MBean 域名
    String getDomain();
}
